
## Introduction

Even well-written methods become hard to maintain when files and projects are organized inconsistently.

This post covers practical structure rules for teams.

## 1) Organize class members consistently

A common order:

1. constants / static readonly fields
2. private fields
3. constructors
4. public properties
5. public methods
6. private methods

Consistency reduces navigation time and review friction.

## 2) Keep related logic close together

Private helper methods should appear near the public method that uses them.

Avoid scattering related logic across long files.

## 3) One class per file (most of the time)

Use file names that match class names.

- `OrderService.cs` -> `OrderService`
- `OrderNotFoundException.cs` -> `OrderNotFoundException`

Exception: tiny related types such as a request record near a small service.

## 4) Avoid overusing regions

If a class requires many `#region` blocks to be readable, the class is likely too large.

Refactor by extracting smaller cohesive classes.

## 5) Keep project boundaries clear

A clean architecture baseline:

- Domain: entities, value objects, domain rules
- Application: use cases, DTOs, interfaces, validators
- Infrastructure: databases, external APIs, file storage
- WebApi: controllers, middleware, composition root

This separation makes ownership and dependencies explicit.

## 6) Comments: explain why, not what

### Bad comment

```csharp
// Check if user is admin
if (user.Role == Role.Admin)
{
    // ...
}
```

### Better code and better comment style

```csharp
if (user.IsAdmin)
{
    // Discount capped at 30% due to compliance policy REG-2024-117
    discount = Math.Min(discount, 0.30m);
}
```

Comment only when context or business rule is not obvious.

## 7) Document public APIs with XML comments

```csharp
/// <summary>
/// Retrieves an order by its unique identifier.
/// </summary>
/// <param name="id">The order ID.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The order, or null if not found.</returns>
public Task<Order?> GetByIdAsync(int id, CancellationToken ct);
```

## 8) Delete commented-out code

Version control already preserves history. Dead commented blocks make files noisy and misleading.

## Summary

Code organization and documentation are force multipliers. Clear structure plus intentional comments makes large C# codebases easier to evolve safely.


Organize C# projects and classes for maintainability, and write comments that explain why instead of what.

C# Code Organization and Documentation Without Noise — Clean Code


# Choosing Between Struct, Class, and Collections in ASP.NET Core: A Practical Decision Matrix

In a typical three-tier ASP.NET Core API (API, Service, Data/Proxy), choosing between `struct`, `class`, and different collection types can impact performance, maintainability, and correctness. Here’s a decision matrix with real-world C# examples for each scenario.

## How Much Data/Size: Struct vs Class?

**General Rule:**

- Use `struct` for small, immutable value types (typically ≤16 bytes, up to 2–4 fields, no reference-type fields).
- Use `class` for larger objects (more than 16 bytes, many fields, or containing reference types).

**Why?**

- Small structs are fast to copy and store inline (on the stack or inside arrays/objects).
- Large structs (over 16 bytes or 3–4 fields) become expensive to copy, so use `class` to avoid performance issues.

**Microsoft’s guideline:**

> "A struct should be less than 16 bytes and ideally immutable. If it’s larger, use a class instead." ([.NET docs](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/struct))

## Decision Matrix

| Scenario                                    | Choice                       | Reasoning                                                                                 |
| ------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------- |
| Small value object (e.g., Money, Point)     | struct inside class          | Inline storage, zero extra allocations, fast, avoids heap allocation, value semantics     |
| Large value object (>16 bytes, many fields) | class inside class           | Copying large structs is expensive; class avoids unnecessary copying, reference semantics |
| Collection of small data                    | List<struct>                 | Compact, cache-friendly, no per-item heap allocation, efficient for value types           |
| Collection of large data                    | List<class>                  | Avoids copying large objects, allows sharing references, better for polymorphism          |
| Shared mutable state                        | class inside class           | Multiple references to same object, enables shared state and mutation                     |
| Immutable data (readonly)                   | readonly struct inside class | Best performance + safety, thread-safe, no accidental mutation, value semantics           |

---

## 1. Small Value Object (e.g., Money, Point)

**Use:** `struct` inside a class

```csharp
public struct Point
{
    public int X { get; }
    public int Y { get; }
    public Point(int x, int y) => (X, Y) = (x, y);
}

public class Shape
{
    public Point Center { get; set; }
}
```

**Why?**

- No heap allocation for `Point`.
- Value semantics (copy by value).

---

## 2. Large Value Object (>16 bytes, many fields)

**Use:** `class` inside a class

```csharp
public class Address
{
    public string Street { get; set; }
    public string City { get; set; }
    public string State { get; set; }
    public string Zip { get; set; }
    public string Country { get; set; }
}

public class Customer
{
    public Address ShippingAddress { get; set; }
}
```

**Why?**

- Avoids expensive copying of large structs.
- Reference semantics.

---

## 3. Collection of Small Data

**Use:** `List<struct>`

```csharp
public struct Pixel
{
    public byte R, G, B;
    public Pixel(byte r, byte g, byte b) => (R, G, B) = (r, g, b);
}

public class Image
{
    public List<Pixel> Pixels { get; set; } = new List<Pixel>();
}
```

**Why?**

- Compact, cache-friendly storage.
- No per-item heap allocation.

---

## 4. Collection of Large Data

**Use:** `List<class>`

```csharp
public class Document
{
    public string Title { get; set; }
    public string Content { get; set; }
}

public class Library
{
    public List<Document> Documents { get; set; } = new List<Document>();
}
```

**Why?**

- Avoids copying large objects.
- Allows sharing and polymorphism.

---

## 5. Shared Mutable State

**Use:** `class` inside a class

```csharp
public class Counter
{
    public int Value { get; set; }
}

public class Game
{
    public Counter Score { get; set; } = new Counter();
}

// Multiple references can share the same Counter instance
```

**Why?**

- Multiple references to the same object.
- Enables shared, mutable state.

---

## 6. Immutable Data (readonly)

**Use:** `readonly struct` inside a class

```csharp
public readonly struct Temperature
{
    public double Celsius { get; }
    public Temperature(double celsius) => Celsius = celsius;
}

public class WeatherReport
{
    public Temperature Current { get; }
    public WeatherReport(Temperature current) => Current = current;
}
```

**Why?**

- Thread-safe, no accidental mutation.
- Best performance for small, immutable data.

---

## Summary Table

| Scenario                 | Use This                     |
| ------------------------ | ---------------------------- |
| Small value object       | struct inside class          |
| Large value object       | class inside class           |
| Collection of small data | List<struct>                 |
| Collection of large data | List<class>                  |
| Shared mutable state     | class inside class           |
| Immutable data           | readonly struct inside class |

**Tip:**

- Use `struct` for small, immutable, value-like data (≤16 bytes, no inheritance, no shared state).
- Use `class` for large objects, shared/mutable state, or when reference semantics are needed.
- Use `readonly struct` for immutable value types to prevent accidental mutation.
- Use collections of structs for small, frequently accessed data; use collections of classes for large or polymorphic data.

---

**Have questions or want to see more advanced scenarios? Leave a comment below!**


A practical guide for ASP.NET Core developers on when to use struct, class, and collections, with real-world C# examples for each scenario.

Choosing Between Struct, Class, and Collections in ASP.NET Core: A Practical Decision Matrix


## Introduction

Production code fails. Clean code does not pretend failures do not exist; it handles them explicitly and consistently.

## 1) Use exceptions correctly

### Do not use exceptions for normal control flow

```csharp
// BAD
public int Parse(string input)
{
    try { return int.Parse(input); }
    catch { return -1; }
}

// GOOD
public int? Parse(string input)
    => int.TryParse(input, out var result) ? result : null;
```

### Throw specific exceptions

```csharp
public class OrderNotFoundException(int orderId)
    : Exception($"Order with ID {orderId} was not found.")
{
    public int OrderId { get; } = orderId;
}
```

Specific exception types improve logging, diagnosis, and mapping to HTTP responses.

## 2) Never swallow exceptions silently

```csharp
try
{
    await ProcessOrderAsync(orderId, ct);
}
catch (Exception ex)
{
    _logger.LogError(ex, "Failed to process order {OrderId}", orderId);
    throw;
}
```

If you catch, either:

- recover meaningfully, or
- enrich and rethrow

## 3) Standardize API errors with ProblemDetails

```csharp
public class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext context,
        Exception exception,
        CancellationToken ct)
    {
        logger.LogError(exception, "Unhandled exception");

        var details = new ProblemDetails
        {
            Status = StatusCodes.Status500InternalServerError,
            Title = "An unexpected error occurred",
            Type = "https://tools.ietf.org/html/rfc9110#section-15.6.1"
        };

        context.Response.StatusCode = details.Status.Value;
        await context.Response.WriteAsJsonAsync(details, ct);
        return true;
    }
}
```

A consistent response structure helps API clients and monitoring tools.

## 4) Validate input at boundaries

Boundary validation keeps invalid data from leaking deep into the domain.

### API request validation (FluentValidation)

```csharp
public class CreateOrderRequestValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderRequestValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(i => i.Quantity).GreaterThan(0);
            item.RuleFor(i => i.Price).GreaterThan(0);
        });
    }
}
```

### Guard clauses inside services/domain

```csharp
public class OrderService(IOrderRepository repository)
{
    public async Task<Order> GetByIdAsync(int id, CancellationToken ct)
    {
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(id);

        return await repository.GetByIdAsync(id, ct)
            ?? throw new OrderNotFoundException(id);
    }
}
```

## 5) Prefer immutability for safety

```csharp
public record OrderDto(int Id, string CustomerName, decimal Total, DateTime CreatedAt);

public readonly record struct OrderId(int Value);
public readonly record struct CustomerId(int Value);
```

Strong types and immutable models reduce accidental state bugs.

## Summary

Reliable C# systems combine:

- clear validation boundaries
- specific exceptions
- structured error responses
- immutable and strongly-typed models

This approach makes failures understandable and recoverable.


Build resilient C# APIs with specific exceptions, ProblemDetails, validation boundaries, and immutable models.

C# Error Handling and Defensive Coding in ASP.NET Core — Clean Code


## Table of Contents

1. [Quick Answer](#quick-answer)
2. [What ConfigureAwait(false) Actually Changes](#what-configureawaitfalse-actually-changes)
3. [Why Deadlocks Happen with .Result and .Wait()](#why-deadlocks-happen-with-result-and-wait)
4. [3-Tier ASP.NET Core API Example](#3-tier-aspnet-core-api-example)
5. [Why ASP.NET Core Usually Does Not Need ConfigureAwait(false)](#why-aspnet-core-usually-does-not-need-configureawaitfalse)
6. [Where ConfigureAwait(false) Still Matters](#where-configureawaitfalse-still-matters)
7. [When NOT to Use ConfigureAwait(false)](#when-not-to-use-configureawaitfalse)
8. [.NET 8: ConfigureAwaitOptions](#net-8-configureawaitoptions)
9. [Blocking vs await: Complete Comparison](#blocking-vs-await-complete-comparison)
10. [Practical Rules You Can Apply Today](#practical-rules-you-can-apply-today)

---

## Quick Answer

- `ConfigureAwait(false)` tells `await` to not capture the current `SynchronizationContext`.
- Continuations resume on any available thread pool thread.
- In ASP.NET Core, there is no request `SynchronizationContext`, so `ConfigureAwait(false)` is usually a functional no-op in app code.
- In reusable library code, still use it consistently because callers might be WPF, WinForms, or older ASP.NET Framework.

---

## What ConfigureAwait(false) Actually Changes

Default `await` behavior is equivalent to `ConfigureAwait(true)`.

```csharp
async Task<string> GetDataAsync(string url)
{
    using var client = new HttpClient();

    // Do not capture caller context
    string data = await client.GetStringAsync(url).ConfigureAwait(false);
    return data;
}
```

Without `ConfigureAwait(false)`:

1. Capture current `SynchronizationContext` (if one exists).
2. Suspend method and return thread to caller.
3. When task finishes, continuation posts back to captured context.

With `ConfigureAwait(false)`:

1. Do not capture `SynchronizationContext`.
2. Suspend method and return thread to caller.
3. Continuation runs on whatever thread is available.

---

## Why Deadlocks Happen with .Result and .Wait()

Classic deadlock pattern in UI apps:

```csharp
// Library method without ConfigureAwait(false)
public async Task<string> FetchAsync(string url)
{
    using var client = new HttpClient();
    return await client.GetStringAsync(url);
}

// UI thread caller (WPF/WinForms)
public string LoadSynchronously()
{
    // Blocks UI thread
    return FetchAsync("https://example.com").Result;
}
```

What goes wrong:

- `.Result` blocks the UI thread.
- `await` continuation tries to return to UI context.
- UI thread is blocked and cannot run continuation.
- Both sides wait forever.

Adding `ConfigureAwait(false)` inside the async method can break that cycle because continuation no longer depends on UI context.

```csharp
public async Task<string> FetchAsync(string url)
{
    using var client = new HttpClient();
    return await client.GetStringAsync(url).ConfigureAwait(false);
}
```

Important: this does not make `.Result` a good pattern. The right fix is still to use `await` end-to-end.

---

## 3-Tier ASP.NET Core API Example

Let us use a simple API with Controller -> Service -> Repository.

### Repository

```csharp
public interface IWeatherRepository
{
    Task<string> GetRawForecastAsync(CancellationToken ct);
}

public sealed class WeatherRepository : IWeatherRepository
{
    private readonly HttpClient _http;

    public WeatherRepository(HttpClient http)
    {
        _http = http;
    }

    public async Task<string> GetRawForecastAsync(CancellationToken ct)
    {
        // In ASP.NET Core app code, ConfigureAwait(false) is optional.
        return await _http.GetStringAsync("https://example.com/forecast", ct);
    }
}
```

### Service

```csharp
public interface IWeatherService
{
    Task<WeatherDto> GetForecastAsync(CancellationToken ct);
}

public sealed class WeatherService : IWeatherService
{
    private readonly IWeatherRepository _repo;

    public WeatherService(IWeatherRepository repo)
    {
        _repo = repo;
    }

    public async Task<WeatherDto> GetForecastAsync(CancellationToken ct)
    {
        string raw = await _repo.GetRawForecastAsync(ct);
        return new WeatherDto
        {
            Summary = raw,
            RetrievedAtUtc = DateTime.UtcNow
        };
    }
}

public sealed class WeatherDto
{
    public string Summary { get; set; } = string.Empty;
    public DateTime RetrievedAtUtc { get; set; }
}
```

### Controller

```csharp
[ApiController]
[Route("api/weather")]
public sealed class WeatherController : ControllerBase
{
    private readonly IWeatherService _service;

    public WeatherController(IWeatherService service)
    {
        _service = service;
    }

    [HttpGet]
    public async Task<ActionResult<WeatherDto>> Get(CancellationToken ct)
    {
        WeatherDto dto = await _service.GetForecastAsync(ct);
        return Ok(dto);
    }
}
```

### Registration (Program.cs)

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddHttpClient<IWeatherRepository, WeatherRepository>();
builder.Services.AddScoped<IWeatherService, WeatherService>();

var app = builder.Build();
app.MapControllers();
app.Run();
```

This works perfectly without `ConfigureAwait(false)` in app layers because ASP.NET Core does not install a request `SynchronizationContext`.

---

## Why ASP.NET Core Usually Does Not Need ConfigureAwait(false)

ASP.NET Core behavior:

- `SynchronizationContext.Current` is usually `null`.
- `await` continuations already run on thread pool threads.
- There is no old request-thread affinity like ASP.NET Framework.

So in Controller/Service/Repository inside ASP.NET Core app code, adding `ConfigureAwait(false)` usually does not change runtime behavior.

Still, teams sometimes keep it in app code for consistency with shared libraries. That is a style choice, not a requirement.

---

## Where ConfigureAwait(false) Still Matters

It matters most in reusable libraries.

```csharp
public sealed class ExternalApiClient
{
    private readonly HttpClient _http;

    public ExternalApiClient(HttpClient http)
    {
        _http = http;
    }

    // Library code: always avoid capturing caller context
    public async Task<string> FetchDataAsync(string url, CancellationToken ct)
    {
        using var response = await _http.GetAsync(url, ct).ConfigureAwait(false);
        response.EnsureSuccessStatusCode();

        string content = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
        return content;
    }
}
```

Why this is safer:

- Library cannot assume caller environment.
- Caller may be WPF, WinForms, Xamarin, or legacy ASP.NET Framework.
- Avoids context capture overhead and reduces deadlock risk for bad sync callers.

---

## When NOT to Use ConfigureAwait(false)

Do not use it when continuation must run on a context-bound thread.

Examples:

1. WPF/WinForms event handlers that update UI controls after `await`.
2. Code paths that depend on context-specific state in older frameworks.

```csharp
// WPF/WinForms example
private async void BtnLoad_Click(object sender, EventArgs e)
{
    string text = await _client.FetchDataAsync("https://example.com", CancellationToken.None);
    // Resume on UI context so control access is safe.
    txtOutput.Text = text;
}
```

If you write UI app code, default `await` is typically the correct behavior in event handlers.

---

## .NET 8: ConfigureAwaitOptions

In .NET 8+, you can use flags-based options.

```csharp
// Equivalent intent to ConfigureAwait(false)
await task.ConfigureAwait(ConfigureAwaitOptions.None);

// Guarantee asynchronous continuation
await task.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
```

Common options:

- `None`: do not capture context.
- `ContinueOnCapturedContext`: capture and resume on context.
- `ForceYielding`: force asynchronous continuation.
- `SuppressThrowing`: advanced scenario, avoid automatic exception rethrow.

For most code, simple `ConfigureAwait(false)` remains easy to read and widely understood.

---

## Blocking vs await: Complete Comparison

| Approach                        | Blocks Thread? | Deadlock Risk with SyncContext? | Scales Under Load? | Recommendation                    |
| ------------------------------- | -------------- | ------------------------------- | ------------------ | --------------------------------- |
| `await task`                    | No             | No                              | Yes                | Always prefer                     |
| `task.Result`                   | Yes            | Yes                             | No                 | Avoid                             |
| `task.Wait()`                   | Yes            | Yes                             | No                 | Avoid                             |
| `task.GetAwaiter().GetResult()` | Yes            | Yes                             | No                 | Only last-resort bootstrap/legacy |

Even in ASP.NET Core where deadlock risk is lower, blocking still burns worker threads and hurts throughput.

---

## Practical Rules You Can Apply Today

1. Prefer async all the way: avoid sync-over-async wrappers.
2. In ASP.NET Core app layers, `ConfigureAwait(false)` is optional.
3. In reusable library/NuGet code, apply `ConfigureAwait(false)` on every await.
4. In UI event handlers, do not use `ConfigureAwait(false)` if you must update controls after await.
5. If legacy code must block, use `.GetAwaiter().GetResult()` rather than `.Result`, and keep that boundary as small as possible.

If you remember one line: use `await` everywhere you can, and use `ConfigureAwait(false)` where your code should not care about the caller's context.


Learn exactly what ConfigureAwait(false) does, when it prevents deadlocks, why ASP.NET Core usually does not need it, and how to apply it correctly in reusable library code.

ConfigureAwait(false) in C# and ASP.NET Core: Deadlocks, 3-Tier API, and Library Rules

Master SynchronizationContext, understand how .Result and .Wait() cause deadlocks in WPF/WinForms/ASP.NET Framework, and why ASP.NET Core eliminated this problem entirely.

ASP.NET Core

C# Code Organization and Documentation Without Noise — Clean Code

Choosing Between Struct, Class, and Collections in ASP.NET Core: A Practical Decision Matrix

C# Error Handling and Defensive Coding in ASP.NET Core — Clean Code

ConfigureAwait(false) in C# and ASP.NET Core: Deadlocks, 3-Tier API, and Library Rules

C# Deadlocks and SynchronizationContext — Why ASP.NET Core Doesn't Have It

Subscribe for Updates